Quickstart Guide
Initialize DecisionNode, record your first decision, and search for it — all in under a minute.
Install and initialize
npm install -g decisionnode cd your-project decide init
This registers your project in the global decision store at ~/.decisionnode/.decisions/.
Set up your API key
Semantic search requires a Gemini API key (free tier available). Run setup and paste your key when prompted:
decide setup
Get a free key from Google AI Studio, then paste it in. The key is saved automatically to ~/.decisionnode/.env.
Capture your first decision
decide add
The CLI prompts you for:
- Scope — the architectural domain this decision belongs to (e.g. UI, Backend, API, Security, Infrastructure). Scopes group related decisions together — each scope becomes its own JSON file.
- Decision — a clear, actionable statement of what was decided.
- Rationale (optional) — the reasoning behind the decision.
- Constraints (optional) — specific rules that must be followed, comma-separated.
Decision: Use Tailwind CSS for all styling
Rationale (optional): Consistent design tokens, easy for AI to generate correct classes
Constraints (optional): No arbitrary values like w-[37px], use @apply only for base components
You can also skip the prompts and add in one command:
decide add -s UI -d "Use Tailwind CSS for all styling" -r "Consistent tokens" -c "No arbitrary values"
API_KEY_INVALID or API Key not found after adding a decision, your Gemini API key is missing or incorrect. Run decide setup to set a valid key. The decision is still saved — only the auto-embedding step fails, and you can re-embed later with decide embed.Verify it was saved
decide list
You should see your decision listed under the UI scope with its ID (e.g. ui-001).
Search for it
decide search "how should we style components?"
DecisionNode embeds your query and compares it against stored decisions using cosine similarity. Your Tailwind decision should come back as the top match.
Connect your AI client
For Claude Code, run this once to register the MCP server:
claude mcp add decisionnode -s user decide-mcp
Restart Claude Code after running this. Your AI can now call search_decisions before writing code and add_decision when you agree on a new approach. For other clients, see the MCP setup guide.